<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Strict//EN">
<html>

<head>
<meta http-equiv="Content-Language" content="en-us">
<title>Explicit and non-explicit calls</title>
<link rel="stylesheet" type="text/css" href="../style.css">
</head>

<body>

<div align="center">
<table class=allEncompassingTable >
 <tr>
  <td >
<p><a href="../index.html" TARGET="_top"><img src="images/homeImg.png"></a></p>



<h1>Explicit and non-explicit calls</h1>

<p>CoppeliaSim's main functionality is handled with calls or commands of following type: sim.handleXXX or sim.resetXXX (e.g. <a href="regularApi/simHandleCollision.htm">sim.handleCollision</a>, <a href="regularApi/simResetCollision.htm">sim.resetCollision</a>, etc.). The <em>regular</em> argument that the command is expecting is a handle of a general-type object (e.g. a handle of a <a href="collisionDetection.htm">collision object</a>, a handle of a <a href="distanceCalculation.htm">distance object</a>, etc.). Imagine you have registered a collision object &quot;robotCollision&quot; through the <a href="collisionDetection.htm">collision detection dialog</a>. If you now wish to check the collision state of that object, you can write following code:<br>
</p>

<pre class=lightRedBox>collisionObjectHandle=sim.getCollisionHandle(&quot;robotCollision&quot;)<br>collisionState=sim.handleCollision(collisionObjectHandle)</pre>

<p>The first line retrieves the handle of the collision object named &quot;robotCollision&quot; (for the exact mode of operation of handle retrieval, refer to the section on <a href="accessingGeneralObjects.htm">accessing objects programmatically</a>). The second line handles the collision object explicitely (i.e. it performs collision detection on that specific collision object). In that case the collision object has to be flagged as <strong>explicit handling</strong>, otherwise an error is generated.<br>
</p>

<p>Above same two commands can also handle objects in a non-explicit way: instead of using the collision object handle as argument, one can also use the <strong>sim.handle_all</strong> argument:<br>
</p>

<pre class=lightRedBox>
sim.handleCollision(sim.handle_all)</pre>


<p>The <strong>sim.handle_all</strong> argument allows handling all registered collision objects at once. Here, collision objects are handled in a non-explicit way.
</p>

<p>When registering general-type objects (e.g. collision objects), then you don't need any specific line of code to handle the objects, because the <a href="mainScript.htm">main script</a> is taking care of that (register a new collision object by specifying two <a href="entities.htm">entities</a> that should be checked for collision, run the <a href="simulation.htm">simulation</a> and move one of the two entities over the other: collision will be detected and the two entities will appear in a different color to indicate collision). Indeed, the <a href="mainScript.htm">main script</a> contains following default code:<br>
</p>

<pre class=lightRedBox>sim.handleCollision(sim.handle_all_except_explicit)<br>sim.handleDistance(sim.handle_all_except_explicit)<br>sim.handleProximitySensors(sim.handle_all_except_explicit)<br>...</pre>

<p>The commands' argument is <strong>sim.handle_all_except_explicit</strong>. It has the same effect as <strong>sim.handle_all</strong>, with following exception: objects marked as <strong>explicit handling</strong> will not be handled. Most general-type objects can be marked as <strong>explicit handling</strong>. When marked so, they will be handled only if the command is called using the object handle (e.g. sim.handleCollision(collisionObjectHandle)) or if the command is called with the <strong>sim.handle_all</strong> argument (e.g. sim.handleCollision(sim.handle_all)).<br>
</p>

<p>By default, the <strong>explicit handling</strong> flag is disabled, which means that by default general-type objects are handled by the main script. However if a <a href="childScripts.htm">child script</a> wishes (or needs) to handle objects itself, then the <strong>explicit handling</strong> flag should be enabled, otherwise an error is generated. Usually objects are handled explicitely only if a child script requires a fresh result of a calculation several times in a same simulation pass (otherwise the child script can use commands like <a href="regularApi/simReadCollision.htm">sim.readCollision</a>, <a href="regularApi/simReadDistance.htm">sim.readDistance</a>, <a href="regularApi/simReadProximitySensor.htm">sim.readProximitySensor</a>, etc.). One the other hand, child scripts should never use the <strong>sim.handle_all</strong> or <strong>sim.handle_all_except_explicit</strong> argument without a good reason! Following figures illustrate explicit and non-explicit calls:<br>
  <br>
</p>

<p align=center><img src="images/explicitHandling1.jpg"></p>
<p class=imageLabel>[CollisionObject1 handled (i.e. calculated) by the default main script (non-explicit handling), and result read in a child script]</p>
<br>

<p align=center><img src="images/explicitHandling2.jpg"></p>
<p class=imageLabel>[CollisionObject1 handled (i.e. calculated) by a child script (explicit handling)]</p>
<br>


<br>
<h3 class=recommendedTopics>Recommended topics</h3>
<li><a href="mainScript.htm">The main script</a></li>
<li><a href="childScripts.htm">Child scripts</a></li>
<br>
<br>
 </tr>
</table> 
</div>  
  
  
</body>

</html>
